home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / errins.zip / ERRINSP.DOC < prev    next >
Text File  |  1992-04-01  |  17KB  |  393 lines
  1. Error Inspector version 1.0
  2. Diagnostic error handler for Clipper 5.01
  3. Copyright (c) 1991, 1992 Nantucket Corporation.  All rights reserved
  4.  
  5.    The Error Inspector is a diagnostic error handler for Clipper 5.0.
  6.    It can be used to diagnose errors during development or as an
  7.    educational aid to learn about Clipper's Error System. As a
  8.    developer, you stand to benefit from using this replacement error
  9.    handler during production, but not necessarily in a final shipping
  10.    version of your software. Because this is a development utility,
  11.    we've made it simple for you to use the Error Inspector in your
  12.    applications and remove it with a minimum of effort.
  13.    
  14. ========================================================================
  15. 1. Contents
  16.    
  17.    The following topics are covered in this documentation file:
  18.    
  19.    1.Contents
  20.    2.Overview of the Error Inspector
  21.    3.Installing the Error Inspector Files
  22.    4.Linking the Error Inspector Files
  23.    5.Programming for the Error Inspector
  24.    6.Implementation Notes
  25.    
  26. ========================================================================
  27. 2. Overview of the Error Inspector
  28.    
  29.    The Error Inspector is supplied as an alternate error handler
  30.    which may be used as a replacement for Clipper 5.0's default error
  31.    handler DefError(). When an error is encountered, the Error
  32.    Inspector intervenes and an initialization window is displayed on
  33.    the screen. Once initialization is complete, the Error object's
  34.    instance variables are displayed and a lightbar menu appears at
  35.    the top of the screen. The menu may be activated at any time by
  36.    pressing F10.
  37.    
  38.    The menu consists of the following submenus:
  39.    
  40.    Response
  41.    --------
  42.    
  43.    This menu allows you to choose the possible responses to an error
  44.    condition. Only the applicable responses to the condition will be
  45.    available; all others will be greyed out.
  46.    
  47.    Break (Ctrl-B) - This option executes a BREAK command, passing the
  48.    current Error object to the outer enclosing sequence. Break is
  49.    always available.
  50.    
  51.    Default - Some Error objects set the instance variable
  52.    oError:canDefault to true, indicating that some default recovery
  53.    is possible. When the Default option is availble, selecting it
  54.    will terminate the Error Inspector and request that the error be
  55.    handled in the default manner.
  56.    
  57.    Retry (Ctrl-R) - The Retry option is available only when the
  58.    oError:canRetry instance variable is set to true, indicating that
  59.    the operation generating the error can be retried. Selecting the
  60.    Retry option will terminate the Error Inspector and retry the
  61.    operation that failed.
  62.    
  63.    Substitute - If selected, you will be prompted for a substitute
  64.    value to return to the subsystem generating the error. Enter any
  65.    macro-compilable Clipper expression. Note that strings must be
  66.    enclosed in quotes, and LOCAL and STATIC variables can not appear
  67.    in this expression. The Error Inspector will terminate and return
  68.    the substitute value to the code generating the error.
  69.    
  70.    Quit (Alt-F4) - Quit returns you to DOS by executing a QUIT
  71.    command. QUIT automatically closes all files and removes VM
  72.    temporary swapfiles, so this is not a particularly dangerous way
  73.    to exit the application. However, you may find that many of your
  74.    program components will not respond happily to half-written
  75.    transactions.
  76.    
  77.    
  78.    
  79.    View
  80.    ----
  81.    
  82.    All of the options under the View menu change the contents of the
  83.    desktop. The up and down arrows allow you to scroll through the
  84.    desktop's data, and a scroll bar to the right indicates your
  85.    current position in the viewed data. A checkmark to the left of a
  86.    View menu option indicates that the option is currently being
  87.    displayed on the desktop.
  88.    
  89.    Callstack (Ctrl-F1) - The Callstack is a list containing the names
  90.    and line numbers of all pending activations at the point in the
  91.    application where the error occurred. The topmost activation
  92.    listed in the callstack is from the Error Inspector (ERRINSP). The
  93.    error that the Error Inspector is reporting occured just below the
  94.    (b)ERRORSYS activation.
  95.    
  96.    Description (Ctrl-F2) - The Description view polls the database of
  97.    descriptions provided with the Error Inspector (ErrInfo.dbf,
  98.    ErrInfo.dbt, and ErrInfo.ntx). The Error Inspector will display
  99.    the appropraiate description from the Clipper 5.01 Norton
  100.    Guides(tm) for the error encountered. If the database is not
  101.    found, then the Description option is not selectable (see
  102.    "Implementation Notes" at the end of this file for more
  103.    information).
  104.    
  105.    Environment (Ctrl-F3) - The Environment view shows the level of
  106.    certain system resources when the error occurred. Available memory
  107.    levels, disk space, file handles, and other resources are found
  108.    here. Remember that these values reflect the system's state just
  109.    after the error occurred and do not necessarily represent the
  110.    current Error Inspector state.
  111.    
  112.    Error Object (Ctrl-F4) - This option shows the settings of all of
  113.    the instance variables in the Error object. A complete description
  114.    for each of these can be found in The Guide to Clipper Norton
  115.    Guide supplied with Clipper 5.01. Note that, where possible,
  116.    numerics are expanded to descriptions (i.e. if e:genCode equals
  117.    14, the Error Inpector displays "14:No Variable").
  118.    
  119.    Sets (Ctrl-F5) - Just as the Environment view shows information
  120.    about system-wide resources, the Sets option shows information
  121.    about Clipper-wide resources. See the SET() funciton description
  122.    in the The Guide to Clipper Norton Guide supplied with Clipper
  123.    5.01 for information about each setting shown here.
  124.    
  125.    Work Areas (Ctrl-F6) - The Work Areas option provides information
  126.    on all open database work areas at the time the error occurred.
  127.    File structures, indexes, current record information, and select
  128.    status are all profiled on this screen.
  129.    
  130.    
  131.    
  132.    Options
  133.    -------
  134.    
  135.    The Options menu is where miscellaneous options are located.
  136.    
  137.    NETERR() - By selecting NETERR() you toggle the NETERR() flag on
  138.    or off. When NETERR() is set to true, a checkmark appears to the
  139.    left of the option name. NETERR() is completely described in The
  140.    Guide to Clipper Norton Guide supplied with Clipper 5.01.
  141.    
  142.    DOS Shell (Ctrl-O) - By selecting this menu option, you can
  143.    temporarily exit your application and return to DOS. When you type
  144.    the EXIT command from the DOS shell, you are returned to the Error
  145.    Inpector screen. See the "Implementation Notes" at the end of this
  146.    document if you do not have enough memory to shell to DOS.
  147.    
  148.    View App Screen (Ctrl-V) - Before the Error Inspector begins
  149.    setting up all of the views, it saves the screen image. You may
  150.    look at the image at any time with this option. Any key will
  151.    return you to the Error Inspector.
  152.    
  153.    Write Log File (Ctrl-W) - This option allows you to write the
  154.    contents of all views to a text file. A default file name is
  155.    created from the date and time with the extention (.rip). You may
  156.    write the log file to any file you wish. If you choose a filename
  157.    that exists, you will be asked if you wish to overwrite the file.
  158.    
  159.  
  160. ========================================================================
  161. 3. Installing Error Inspector Files
  162.    
  163.    Prior to installation, the Error Inspector consists of the
  164.    following two files:
  165.    
  166.    -------------------------------------------------------
  167.    Filename        Description
  168.    -------------------------------------------------------
  169.    ERRINSP.DOC     Documentation (This file)
  170.    ERRINSP.ZIP     The Error Inspector
  171.    -------------------------------------------------------
  172.    
  173.    To install the Error Inspector files on your machine:
  174.    
  175.    1.   Create the \ERRINSP directory:
  176.              C>MD \ERRINSP
  177.    
  178.    2.   Copy this file to the \ERRINSP directory:
  179.              C>COPY [d:][pathspec]ERRINSP.DOC \ERRINSP\*.*
  180.    
  181.    3.   Unzip the error inspector files:
  182.              C>CD \ERRINSP
  183.              C>PKUNZIP [d:][pathspec]ERRINSP
  184.    
  185.    These are the files in the Error Inspector distribution (.zip)
  186.    file, ErrInsp.zip:
  187.    
  188.    -------------------------------------------------------
  189.    Filename        Description
  190.    -------------------------------------------------------
  191.    ERRDEMO.PRG     Demonstration program
  192.    ERRDEMO.RMK     RMAKE script for linking the demonstration
  193.    ERRINSP.PRG     ErrorSys() replacement which installs the error
  194.                    inspector as the default error handler
  195.    ERRINSP.OBJ     ErrInsp.prg, in object code form
  196.    ERRINSP.LIB     Support functions required by the error inspector.
  197.    ERRINFO.DBF     Error Information database containing descriptions
  198.                    of errors generated by Clipper 5.0's various
  199.                    subsystems.
  200.    ERRINFO.DBT     Memo file for the Error Information database.
  201.    ERRINFO.NTX     Index file for the Error Information database.
  202.    SAMPLE.RIP      Sample output
  203.    -------------------------------------------------------
  204.    
  205.    Once these files are in your \ERRINSP directory, you should create
  206.    and run the demo program. An RMAKE file has been provided for this
  207.    purpose. You will have to tell the RMAKE file where your CLIPPER
  208.    root directory is with the /dclipdir: option (usually
  209.    C:\CLIPPER5\):
  210.    
  211.    C>RMAKE ERRDEMO /dclipdir:<clipper root> [/dpll]
  212.    
  213.    When you run the demonstration program, you will be presented with
  214.    a menu of errors that can be created -- the Error du Jour. When
  215.    you select an error, the demo program will generate the error,
  216.    thereby invoking the Error Inspector (see "Overview of the Error
  217.    Inspector" for more information).
  218.    
  219. ========================================================================
  220. 4.   Linking the Error Inspector into Your Application
  221.    
  222.    
  223.    The Error Inspector consists of two parts: a public interface, and
  224.    a library of support routines. The public interface (ErrInsp.prg &
  225.    ErrInsp.OBJ) contains startup code that installs the Error
  226.    Inspector as the default error handler. The function ERRORSYS() in
  227.    ErrInsp.prg posts the Error Inspector root function as the new
  228.    default ERRORBLOCK(). For this reason, ErrInsp.OBJ must appear
  229.    last in your object list, and you must not have previously defined
  230.    ERRORSYS() in your application.
  231.    
  232.    Here are the common ways that the Error Inspector can be linked
  233.    into your application:
  234.    
  235.    1.   To link with .RTLink using positional syntax:
  236.    
  237.    C>RTLINK <appObjectList> ERRINSP,,, <systemLibList> ERRINSP;
  238.    
  239.    2.   To link with .RTLink using freeformat syntax:
  240.    
  241.    C>RTLINK FI <appObjectList>,ERRINSP LIB <systemLibList>,ERRINSP
  242.    
  243.    3.   To link with .RTLink using Base50.PLL and freeformat syntax:
  244.    
  245.    C>RTLINK FI <appObjectList>,ERRINSP LIB <systemLibList>,ERRINSP
  246.    /PLL:BASE50.PLL
  247.    
  248.    4.   To link using MS-Link version 3.65 and above:
  249.    
  250.    C>LINK <appObjectList> ERRINSP,,, <systemLibList> ERRINSP /NOD
  251.    /NOE /SE:512;
  252.    
  253.    Note: These link commands all assume that the LIB, OBJ, and PLL
  254.    environment variables are set to the standard locations.
  255.    
  256. ========================================================================
  257. 5. Programming for the Error Inspector
  258.    
  259.    While there are no special code requirements for using the Error
  260.    Inspector, you can write your programs to be more "error handler
  261.    aware."
  262.    
  263.    The simplest and most dramatic change you can make is to simply
  264.    surround your main menu with a BEGIN SEQUENCE...END structure. It
  265.    is also a good idea to provide some cleanup code in the RECOVER
  266.    section of this BEGIN SEQUENCE...END. This will allow you to issue
  267.    a BREAK(e) after a minor error has occured, yet still remain in
  268.    the program with reasonable assuredness that the error condition
  269.    will no longer affect you.
  270.    
  271.    The complexity of your RECOVER routine is up to you, but remember
  272.    that you have the Error object's information to guide you in
  273.    choosing a complete recovery strategy. This could be as simple as
  274.    falling through to the end of the loop, or as complex as
  275.    reindexing or rebuilding your databases.
  276.    
  277.    Here is a skeletal example of this strategy:
  278.    
  279.    DO WHILE !lTerminated
  280.       BEGIN SEQUENCE
  281.          .
  282.          <application setup>
  283.          .
  284.          Main()             // Main menu, event loop, whatever...
  285.          .
  286.          <application termination code>
  287.          .
  288.          // Made it through sucessfully
  289.          lTerminated := .T.
  290.       RECOVER USING e
  291.          .
  292.          <recovery code>
  293.          .
  294.          IF <condition fatal>
  295.             lTerminated := .T.
  296.          ENDIF
  297.       END SEQUENCE
  298.    ENDDO
  299.    .
  300.    .<application clean up code>
  301.    .
  302.    
  303.    More information on the use of the Error Handler in Clipper can be
  304.    found in the Clipper Manuals; the Norton Guides to Clipper;
  305.    Nantucket News V5 N2, September/October 1990, p3-6; Nantucket News
  306.    V5 N4, January/February 1991, p13-22, and The Nantucket Technical
  307.    Series, "Error Handling Strategies."
  308.    
  309. ========================================================================
  310. 6. Implementation Notes
  311.    
  312.    -----------------------------------------------------------------
  313.    How the Error Inspector locates error descriptions
  314.    
  315.    When you choose View-Description (Ctrl-F2), the Error Inspector
  316.    looks for ErrInfo.dbf, ErrInfo.dbt, and ErrInfo.ntx to find the
  317.    complete description of the error. If for some reason, the Error
  318.    Inspector is unable to locate these files, the Description option
  319.    will be unavailable.
  320.    
  321.    If this occurs, you may have installed the Error Inspector in a
  322.    drive and directory other than C:\ERRINSP. In order to point to
  323.    the correct location of the database files, the EI_ERRINFO_PATH
  324.    manifest constant in ErrInsp.prg should be modified to reflect the
  325.    proper path.
  326.    
  327.    After modification, you will need to recompile ErrInsp.prg. See
  328.    the instructions below.
  329.    
  330.    Note that if, for some reason, the Error Inspector's database,
  331.    memo, or index files are corrupt, the only repair mechanism
  332.    available is to unzip them from the distribution files.
  333.    
  334.    -----------------------------------------------------------------
  335.    Freeing more memory to shell to DOS
  336.    
  337.    There are several third-party libraries that allow you to shell to
  338.    DOS while first swapping used low memory to disk or EMS. If you
  339.    own one of these products, and would like to take advantage of
  340.    their ability to shell to DOS while maximizing free memory, you
  341.    need only change the return value of ShellBlock() in ErrInsp.prg.
  342.    
  343.    The Error Inspector retreives the code block returned by
  344.    ShellBlock() and EVALs it when a shell to DOS is requested. Note
  345.    that the Error Inspector will ensure that the cursor is on and the
  346.    screen is saved before ShellBlock() is EVALed. If you must
  347.    generate an error from your ShellBlock(), issue a BREAK(e).
  348.    
  349.    After modification, you will need to recompile ErrInsp.prg. See
  350.    the instructions below.
  351.    
  352.    -----------------------------------------------------------------
  353.    Instructions for recompiling ErrInsp.prg
  354.    
  355.    Use the following Clipper command to recompile ErrInsp.prg:
  356.    
  357.    C>CLIPPER ERRINSP /n /m /w
  358.    
  359.    -----------------------------------------------------------------
  360.    Errors Encountered from within the Error Inspector,
  361.    ... or When it really hits the fan ...
  362.    
  363.    If, for some reason, the Error Inspector encounters a condition it
  364.    is not prepared to deal with, an ALERT() box is displayed:
  365.    
  366.         The Error Inspector is unable to continue.
  367.         <e:subSystem>/<e:subcode>: <e:description>
  368.    
  369.    You then have the option to QUIT or BREAK. If you choose to QUIT,
  370.    you will find yourself at the DOS prompt. When selecting the
  371.    BREAK, program control is passed to the nearest BEGIN
  372.    SEQUENCE...END construct. If your application does not include
  373.    such a statement block, execution will terminate, returning to
  374.    DOS.
  375.    
  376.    -----------------------------------------------------------------
  377.    The Error Inspector Team
  378.    ------------------------
  379.    
  380.    The Error Inspector was originally developed for the Fall 1991
  381.    Developer Conference. It is writtten entirely in Clipper 5.01
  382.    
  383.            Design: Craig Ogg and Jesse Srogoncik
  384.    Implementation: Jesse Srogoncik
  385.     Documentation: Terry McConnell
  386.      Consultation: Savannah Brentnall, Robert DiFalco,
  387.                    Scott McIntosh, Terry McConnell, David Morgan,
  388.                    Phil Schwartz, and Chris White
  389.    
  390.  
  391.                               *  *  *
  392.  
  393.